import { Callout } from "nextra-theme-docs";
import { APITable } from "../../../components/APITable";

# 히스토리와 동기화하기

**Stackflow**의 네비게이션 로직은 기본적으로 브라우저 히스토리에 의존하지 않아요. History API가 존재하지 않는 React Native, NativeScript 등의 환경에 대응하기 위해서에요. 따라서 브라우저 히스토리를 탐험에 사용하기 위해서는 스택 상태를 브라우저 히스토리와 동기화해줄 필요가 있어요. 해당 기능은 `@stackflow/plugin-history-sync`가 지원해요.

다음 명령어를 통해 `@stackflow/plugin-history-sync`를 설치해요.

```sh npm2yarn copy
npm install @stackflow/plugin-history-sync
```

설치가 완료되면 다음과 같이 `stackflow()` 함수의 `plugins` 필드에 플러그인을 등록해요.

```tsx showLineNumbers filename="stackflow.ts" copy
import { stackflow } from "@stackflow/react";
import { basicRendererPlugin } from "@stackflow/plugin-renderer-basic";
import { historySyncPlugin } from "@stackflow/plugin-history-sync";
import MyActivity from "./MyActivity";
import Article from "./Article";

const { Stack, useFlow } = stackflow({
  transitionDuration: 350,
  activities: {
    MyActivity,
    Article,
  },
  plugins: [
    basicRendererPlugin(),
    basicUIPlugin({
      theme: "cupertino",
    }),
    historySyncPlugin({
      routes: {
        MyActivity: "/my-activity",
        Article: "/articles/:articleId",
      },
      fallbackActivity: () => "MyActivity",
    }),
  ],
  // historySyncPlugin이 해당 옵션을 덮어쓰므로 initialActivity는 더 이상 작동하지 않아요.
  // initialActivity: () => "MyActivity",
});
```

`historySyncPlugin`은 `routes`와 `fallbackActivity` 두 옵션을 받아요.

<APITable>
|                  |            |                                                                                                                                                 |
| ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------  |
| routes           | `object`   | 액티비티와 URL 템플릿을 연결해요. 액티비티의 파라미터를 Path Parameter로 표현할 수 있어요. 만약 액티비티의 파라미터가 해당 URL 템플릿에 없다면 자동으로 Query Parameter로 표현돼요. |
| fallbackActivity | `function` | 첫 진입시에 현재 URL과 매핑되는 URL이 없는 경우 어떤 액티비티로 보낼지 결정해요. 일반적으로 404 페이지를 만들고 여기에 할당해요.                                              |
</APITable>


<Callout type="warning" emoji="⚠️">
  **주의** - Activity parameter가 Path parameter와 매핑할때, 넘어갈 수 있는
  파라미터 값들이 URL-safe 한지 확인이 필요해요. 만약 URL-safe 하지 않은
  특수문자를 사용하는 경우 query parameter가 중복해서 나타날 수 있어요.
</Callout>

<Callout emoji="⚡️">
  서버사이드 렌더링 환경에서는 `window.location` 값이 없으므로 초기 액티비티를 결정할 수 없어요.
  초기 액티비티를 결정하려면 다음과 같이 Stack의 `initialContext`에 `req.path` 필드에 path 값을 넣어주세요.

  ```tsx
  <Stack initialContext={{ req: { path: "/..." } }} />
  ```
</Callout>
